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SUMMARY 

Too many useful computer programs go the way of undocu- 
mented "black boxes" which are treacherous to run. A computer 
report format is set forth to salvage such programs with a mini- 
mum of effort. It is based on the "Liquan" program designed to 
analyze liquid-propellant rocket-engine static firing data. A fea- 
ture to readily accommodate program expansion is also presented— 
the engineering analysis sequence pattern. 
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AVOIDING "BLACK BOX" COMPUTER PROGRAMS 


b y 

Abrom Hisler 

Goddard Space Flight Center 


INTRODUCTION 

No sooner does an engineering computer program become operational than 
the engineer-programmer team, responsible for the program's development, 
must seriously consider the need to document the effort which went into the pro- 
gram. To do otherwise is to risk the chameleon conversion of the new useful 
program into a treacherous "black box." 

Yet, too often computer programs, once developed and checked out, are never 
documented or are not sufficiently well documented. Such programs run the risk 
of becoming "black boxes" if: 

1. The original engineer-programmer team is not available for consultation. 

2. Through the years, this original team has lost their intimate familiarity 
with the program's details. 

Periodic critiques of "black box" programs can be undertaken only with 
great difficulty. Without the documented development effort available, updating 
the program becomes impossible. 

The engineer-programmer team's interest, initially keen to develop a par- 
ticular computer program to meet certain needs, often wanes once the program 
has been developed and attention shifts elsewhere to develop new programs. 

"Black box" programs are treacherous to run because the original assump- 
tions, unique conditions of the computation, and other program idiosyncrasies 
have become unknown "booby trap" quantities. The cost of operating such pro- 
grams grows to include not only the actual computer time wasted but also the 
unwise expenditure of money on engineering designs which reflect an erroneous 
conception of the computer program employed. 

Constructive critiques of "black box" programs are impossible and so is 
the possibility of updating these programs as new state-of-the-art techniques 
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are developed. A well-documented computer program reflects the developmental 
effort which went into the program, permits effective periodic critiques, and can 
readily accommodate new calculation methods. 

The nature of the computer program documentation considered in this re- 
port differs from other similar reports (Ref. 1) in presenting a few features 
which should appeal more to the engineer collaborating with his technical writer- 
editor than to the programmer. The programmer, should he feel so inclined, 
might wish to prepare a computer flow chart (Ref. 1, p. 37), which is usually 
more comprehensible to programmers rather than engineers. 


PREFERABLE FORMATS 

The need to establish a preferable format for a well-documented report on 
computer programs was first pointed out at the Ninth Meeting of the Working 
Group on Design Automation (Ref. 2, p. 24). Although there is nothing startling 
about the "Liquan" computer program documented in this report, it will serve 
mainly to present the essentials of this "preferable format." They include the 
following: 

1. Computer program 

2. Sequential engineering analyses 

3. Decoding and worksheet 

4. Typical input 

5. An additional input format 

6. Typical output 


SEQUENTIAL ENGINEERING ANALYSES 

Although a copy of the computer program is presented in Appendix A, 
reference to the Sequential Engineering Analysis of Appendix B should more 
quickly familiarize the reader with the essence of the program. The equations 
presented are of general utility; but many of the constants, such as the 4.6 in 
the coefficient of thrust equation, refer specifically to the Aerobee 350 sounding 
rocket— in this case, the ratio of exit area to throat area of the nozzle. A sub- 
sequent follow-on program sought to empirically relate the C* function in terms 
of mixture ratio and chamber pressure for later use in an associated propellant 
utilization program, for still subsequent use in a simple 2-D trajectory program. 

A number of additional features present in Appendix A but not shown in 
Appendix B include: 

1. TC - The time at which a particular chamber changes from step opera- 
tion to full operation. This permits a change in the 1^ values so that 
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the propellant flow is markedly increased. The step operation stage is 
employed to avoid the problem of feeding too much propellant into the 
chamber and igniting it after a significant ignition delay period. Were 
this to happen, the chamber would blow up. 

2. TFIN and TFOUT — The fuel temperature, in and out of the cooling jacket, 
is averaged before its specific gravity is computed. 

3. A CFA feature to throw out negative CFA values where the chamber 
pressure has not risen sufficiently to even reach the step operation 
stage. 

These features have not been incorporated into the Sequential Engineering 
Analysis to keep it sufficiently simple for presentation in this report. However, 
these features (and others) would take their respective place in the analysis in 
a followup revision as part of the updating effort. 

It can therefore be seen that, although Appendix B does not reflect every 
detail of the present program, it can nevertheless readily accommodate addi- 
tions and deletions to the program and so grow in complexity but not in confusion. 

Appendix B can also be used as a worksheet to jot down references in their 
appropriate place in the sequence for future inclusion of this matter into the 
program. 

It also permits simpler constructive critique as nebulous areas arise or as 
the conditions, circumstances, and assumptions of the program computation 
change. 

Appendix B also serves as a pivot point. Its analysis can be pivoted in the 
direction of any of the program languages— FORTRAN, MYSTIC, FORAST, etc. 
And, conversely, these computer languages can be translated back into the 
" engineering" language of Appendix B. 


DECODING WORKSHEET 

The Fortran Decoding and Worksheet in Appendix C neatly ties together in 
one chart: 

1 . The input and output, 

2 . The engineering notation with dimensions employed in the Sequential 
Engineering Analysis, 
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3. The blank three columns of card numbers, column numbers, and typical 
values which may be used by the program operator in the manner of a 
worktable for better familiarization with the input of the program. 

It may be appropriate to mention here with respect to engineering notation 
and FORTRAN that a step has been taken to standardize FORTRAN nomenclature 
as it pertains to solid rocket motor design (Ref. 3). 


DATA INPUT 

The data input is presented in two forms: Appendixes D and E. The usual 
order of presentation is shown in the former and, in the latter, a new method 
associates the read input tape card with corresponding data. The latter appendix 
should reduce the time required to prepare new sets of data, especially since 
the data are aligned with the numbered columns at the bottom of the sheet. 
Another advantage of the Appendix E input is to eliminate costly errors which 
occur when misunderstandings arise over the data input. Too often, useless 
program runs are attempted, resulting in wasteful computer time expenditures 
and lost man-hours because of initial unfamiliarity with data input order. 


Typical output is shown in Appendix F. 

FORMAT ADVANTAGES 

With the above formats, less effort is required to document a particular 
computer program; and the computer report so prepared has the following 
advantages : 

1. Presents a bird’s-eye view of the calculation logic and flow. 

2. Affords the opportunity to annotate the engineering analysis flow chart 
with: 

(a) Assumptions, 

(b) Unique conditions, 

(c) Past and future applicable references. 

3. Permits a fast periodic review of the program. 
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4. Involves a minimum of time and effort to familiarize, and refamiliarize 
oneself after a long lapse of time, with the program flow and data input. 

5. Serves to expand the original program as the occasion arises. 

RECAPITULATION 

This computer report then serves two purposes: 

1. To provide the necessary information to utilize the "Liquan" computer 
program to ANalyze LIQUid (LIQU-AN) propellant rocket-engine static 
firing data. 

2. To set forth a computer report format of general applicability which may 
differ markedly from typical computer program reports but which con- 
tains the minimum necessary essentials to adequately document a computer 
program, such as "Liquan." 
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Appendix A 

The Computer Program— Liquan 


$ JOB 1091C003 409H I SLER * A. 
^EXECUTE FORTRA 


* 


* 

XEQ 

* 

XEQ 

* 

LIST 8 

* 

LABEL 


C LIQUAN-A PRELIMINARY ANALYSIS OF LIQUID PROPELLANT ROCKET ENGINE 
C static FIRING DATA-A.HISLER 4 

DIMENSION PC (200) .CFA (200 ) * T I ME < 200 ) * PCDT < 200 ) * PCG ( 200 ) .SPGFAC200) 

1 . TFA ( 200 ) *DPFA ( 200 ) *PFJ(200 > *WDFA( 200) *DPQ< 200) *POJ<200> * WDO < 200 ) * 
2WDT < 200 ) . WDFDT(200 ) * WDODTC2QO ) .WDTDT <200 ) * DELT ( 200 ) * AMRI200 ) *PALT< 
3200 ) , FA (200) * A I SP < 200) • CSTAR < 200) .TFINC200) .TFOUTC2QO) 

10 AIT *0*0 
TWDTDTaO.O 
TWDODT sO • 0 
TWDFDT = 0 • 0 

READ INPUT TAPE 2 * 1 * I A * IB, I C * ID* IE 

1 FORMAJ ( 14*412 ) 

READ INPUT TAPE 2 * 2 • AT * TO . AKWF A ♦ AKWO. TKWFA , TKWO * TC 

2 FORMAT (7F 10*4) 

READ INPUT TAPE 2.14.G 

14 FORMAT (FIO. 4 ) 

READ INPUT TAPE 2 * 3 * ( T I ME ( I ) • I *1,1 A) 

READ INPUT TAPE 2*3*<TFIN(I),I*1,IA> 

READ INPUT TAPE 2* 3 • ( TFOUT ( I ) * I = 1 t I A ) 

READ INPUT TAPE 2.3.<PFJ(I>* 1*1* I A) 

READ INPUT TAPE 2*3*<P0J(I>. 1-1*1 A) 

READ INPUT TAPE 2 * 3 * ( PCG ( I ) ♦ I * 1 * I A ) 

3 FORMAT (7F 10.4) 

SPGO»— 0 • 000833*TO+ 1 .5953 
WRITE OUTPUT TAPE 3*36 
36 FORMAT { 1H1) 

WRITE OUTPUT TAPE 3*47 

47 FORMAT ( 49H WATER CONSTANTS THROAT AREA G-VALUE 0XIDIZER/51H 
1 FUEL OXIDIZER TEMPERATURE) 

WRITE OUTPUT TAPE 3 ♦ 4 * AKWFA * AKWO ♦ AT * G * TO 

4 FORMAT (5F10 .4) 

WRITE OUTPUT TAPE 3*15 

15 FORMAT < 1 HO ) 

WRITE OUTPUT TAPE 3*8 

8 FORMAT ( 1 HO/ 1 05H FLOW RATE MIXTURE 

1 CF THRUST SPECIFIC CSTAR CHAMBER/1 16H OX ID 

2IZER FUEL TOTAL RATIO 

3 IMPULSE PRESSURE TIME) 

DO 11 I *1 * I A 

TFA ( I ) *0.5* ( TF I N ( I )+TFOUT< I ) ) 

SPGFA ( I ) a— O . 00 0508* TFA ( 1)4-1 .0988 
DPFA < I ) =PF J ( I ) -PCG ( I ) 

DPO ( I > »PO J ( 1 ) -PCG ( I ) 

IF ( PCG ( I ) ) 81*81*82 

81 PCI I )=0«0 
GO TO 83 

82 PC Cl) * PCG < I ) + 14.7 

83 GO TO ( 7*5) * IB 

7 READ INPUT TAPE 2 * 2 . ( PALT < J ) , J*1*IA) 

6 CFA ( I)«l .422+1 0.036- (PALTI I )/PC< I ) ) ) *4.6 
GO TO 12 

5 CFA ( Dal .422+ (0.036-14. 7/PC ( I ) )*4.6 
I F ( CFA ( I ) ) 21 * 12* 12 

21 CFA ( I ) a 0 ♦ 0 

12 FA< I )=CFA( I )*AT*PC ( I ) 

I F ( T I ME ( I ) — TC ) 70*60*60 

70 WDF A < I ) =TKWFA*SGRTF ( DPFA ( 1 ) *SPGFA ( I ) ) 

WDO ( I ) »TKWO*SQRTF ( DPO ( I ) *SPGO ) 

GO TO 80 

60 WDF A ( I ) aAKWFA*SQRTF I DPFA< I ) *SPGFA ( I ) > 

WDOID* AKWO*SQRTF ( DPO ( I ) *SPGO ) 

80 WDT < I ) aWDFA ( I ) +WDO ( I ) 

AMR! I ) aWDOC I ) /WDF A ( I ) 

AISPI I ) *FA ( I )/WDT( I ) 

CSTARI I ) = <PC< I )*AT*G)/WDT< I ) 

11 WRITE OUTPUT TAPE 3 • 9. WDO < I ) ♦ WDF A < I ) « WDT < I) * AMR ( I > • CFA ( I ) . FA ( I ) * A I 
1 SP < I ) * CSTAR ( I ) * PC ( I ) * T I ME ( I ) 

9 FORMAT ( F 1 0 • 4 • 2F 12.4.F10.4*F12.4*F14.4* 3F 12.4. FI 1.4) 

WRITE OUTPUT TAPE 3.15 

I A 1 a I A— 1 

DO 50 I * 1 * I A 1 

DELT ( I ) *T I ME ( I + 1 ) — T I ME ( I ) 

CALL TRAP I (PCI 1 + 1 ) *PC( I ) .DELT ( I ) • PCDT I I ) ) 

A I T* A I T+CFA ( 1 ) * AT*PCDT ( I ) 

CALL TRAP I ( WDO ( I + 1 ) * WDO ( I ) . DELT < I ) « WDODT ( I ) ) 

TWDODTaTWDODT+WDODTI I ) 

CALL TRAP I ( WDF A ( I + 1 ) * WDF A Cl), DELT ( I ) * WDFDT ( I ) ) 

TWDFDTaTWDFDT+WDFDTI I ) 

CALL TRAP I ( WDT ( I + 1 ) . WDT ( I ) . DELT ( I ) * WDTDT CD) 

50 T WDTDT * TWDTDT+ WDTDT { I ) 

WRITE OUTPUT TAPE 3.41 *IC 

41 FORMAT 1 30H 350 AEROBEE STATIC FIRING NO 12) 

WRITE OUTPUT TAPE 3*42* ID 

42 FORMAT (24H 350 AEROBEE CHAMBER NO 12) 

WRITE OUTPUT TAPE 3*43* IE 

43 FORMAT (33H AEROBEE PRESSURE DROP SYSTEM NO 12) 

WRITE OUTPUT TAPE 3*44 

44 FORMAT (39H AEROBEE 350 PRESSURE DROP SYSTEM CODE/33 H NO 1-iNJ 

1ECTI0N PRESSURE DR0P/38H NO 2-TANK PRESSURE DROP 

WRITE OUTPUT TAPE 3.15 
WRITE OUTPUT TAPE 3. 13, A IT 

13 FORMAT (37H THE TOTAL IMPULSE OF THIS CHAMBER = F10*2) 

WRITE OUTPUT* TAPE 3*16*TWDFDT 

16 FORMAT (36H THE TOTAL WEIGHT OF FUEL FLOWED IS FI 0.4) 

WRITE OUTPUT TAPE 3,17*TWD0DT 

17 F ORMAT < 40H THE TOTAL WEIGHT OF OXIDIZER FLOWED IS F10.4) 

WRITE OUTPUT TAPE 3*18* TWDTDT 

18 FORMAT <42H THE TOTAL WEIGHT OF PROPELLANT FLOWED IS FlO«4) 

T OTP* TWDFDT + TWDODT 

WRITE OUTPUT TAPE 3.19.T0TP 

19 FORMAT (53H THE COMBINED FUEL AND OXIDIZER PROPELLANT FLOWED IS FIO 
1.4 ) 

GO TO 10 
END 

• LIST 8 

* LABEL 

C TRAPEZOIDAL INTEGRATION 

SUBROUTINE TRAP I < B * C *D ♦ A ) 

A* (B+C) *0.5*D 

RETURN 

END 
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Definition 


Mixture ratio 

Specific impulse 

Total impulse 

Area of thrust cross section of discharge nozzle 

Water flow constant for fuel system— steady state 

Water flow constant for oxidizer system- steady state 

Thrust coefficient = F/A t P n 

Characteristic velocity for rocket motor 

Pressure differential across fuel system 

Pressure differential across oxidizer system 

Time interval 

4-3 

m 

2 

e 

Acceleration due to gravity 

No. of data points 

Do either statement 7(1) or 5(2) 

Firing no. 

Chamber no. 

Pressure drop system no. 

No. of data points - 1 

Chamber pressure, absolute 

Chamber pressure time integral 

Chamber pressure, gage | 

Fuel injection pressure 

Oxidizer injection pressure | 

Pressure at altitude I 

Specific gravity of fuel | 

Specific gravity of oxidizer 

Time 

Temperature of fuel, average | 

Incoming temperature of fuel j 

Exit temperature of fuel 1 

Total flow rate-time integral 

Total oxidizer flow rate-time integral I 

Total fuel flow rate- time integral | 

Oxidizer temperature, average [ 

Initial transient fuel water flow constant 

Initial transient oxidizer water flow constant 

Time of propellant full flow ! 

Fuel flow rate [ 

Oxidizer flow rate 

Total propellant flow rate | 

Fuel flow rate-time integrals | 

Oxidizer flow rate-time integrals | 

Propellant's flow rate-time integrals 

Notation 
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